WIP: 0.9.dev1 by jni · Pull Request #190 · ome/ngff-spec

jni · 2026-08-19T12:48:40Z

0.9.dev1 is intended to be:

0.6rc1
with RFC3
and RFC4
and ~~probably~~ omero fields optional #87

in current WIP this only includes RFC3. I need to get RFC4 in before we merge this.

Edit 1 (2026-08-20): updated title to 0.9.dev1 to reflect discussion and match PEP-440.

Edit 2 (2026-08-21): This PR now contains all of the listed requirements (RFC3, RFC4, #87 omero fields optional) and should be ready to merge to allow implementations to start to be written against it. Some notes below.

notes

The limits removals on coordinate-transformations are the thing I'm least sure about, would appreciate extra eyes there.

In schemas/coordinate_transformations.schema, rotation is defined by a 2, 3, 4, or 5-dimensional rotation matrix. This is incompatible with RFC-3 but cannot be easily extended to an arbitrary number of dimensions.

Possible solutions:

Amend RFC-3 to have a large number of max dimensions (say, 12? 16?), and continue the definition given the arbitrary rotations
For higher-dimensional rotations, allow instead a sequence of 2-axis rotations, which compose into a high-dimensional rotation. (Can higher-dimensional rotations always be decomposed in this way?)
Amend 0.6/RFC-5 to disallow >3D rotations, since they are very uncommon, and can already be decomposed (as a sequence of 2D rotations, because sequences are already a thing.)

I'm also not sure about 6199f0e and the difference to 93c1ba7.

Finally I don't know how to express that orientation can only be present if axis type is "space".

github-actions · 2026-08-19T12:48:51Z

Automated Review URLs

Readthedocs

sbesson · 2026-08-19T12:56:05Z

@jni thanks for starting this work. We're looking forward to having a first rendered version of this specification as well as dev schemas that we can use to validate datasets generated by implementations!

Immediate question: is the next version number 0.9dev1 (as in this PR) or 0.9.dev1 (used in a few public discussions)?

We have no opinion one way or the other, but we have used the latter so far so if the consensus is to move towards the first form, we will need to update our implementation and regenerate sample data /cc @melissalinkert

clbarnes · 2026-08-19T13:28:42Z

is the next version number 0.9dev1 (as in this PR) or 0.9.dev1 (used in a few public discussions)

This came up with the dev versions in 0.6. Because we use python tooling in the build step of the repo, we normalised on PEP440-style version specifiers 0.6.dev0 and 0.6rc0. Overfitting to the language we happen to be using for the build is not ideal, but it's pretty well specified with implementations in many languages, while allowing a lot of flexibility in the information included in a version string. The inconsistency in . between the dev and a/b/rc is annoying, but I suppose it's intended so that you can have a dev version for an alpha release, and so on. This rust crate has a good run-down of the downsides of PEP440.

Standard SemVer would use something like 0.9-dev.1 but, other than .-delimiting, treats string and numeric components of the pre-release version as arbitrary, to be sorted lexicographically and numerically respectively. e.g. dev would come after alpha and beta. It also doesn't allow post-releases (probably fine, a post-release should probably be a patch release) or epochs e.g. if we decided we wanted to switch to calver later (also probably fine).

IMO we should stick with PEP440 (0.9.dev1), or switch to standard SemVer (0.9-dev.1) and separate the versioning of the project from the versioning of the python tooling used to build it, but I don't care too much about which.

melissalinkert · 2026-08-19T15:38:02Z

Just to be clear, then, is the use of 0.9dev1 now fully decided? I need to update glencoesoftware/bioformats2raw#330 and glencoesoftware/raw2ometiff#156 with the agreed-upon version number before merging and tagging release candidates, which we expect to do within the next few days. If the version number is still being discussed, I need to know so that merging/tagging can be delayed until the discussion is resolved.

jni · 2026-08-20T01:03:16Z

Apologies, for the confusion, my confusion indeed stemmed from the inconsistency between 0.6.devN and 0.6rcN noted by @clbarnes above. I think consistency with the 0.6 series makes sense, which means I'll update this PR to match that. In short @melissalinkert @sbesson, let's go with 0.9.dev1, no need to change your outputs, I will update this PR accordingly.

jni · 2026-08-20T06:19:38Z

Here's the current validation test failures:

FAILED tests/test_attributes.py::test_attributes[spec/invalid/image/missing_space_axes] - Failed: DID NOT RAISE ValidationError
FAILED tests/test_attributes.py::test_attributes[spec/invalid/image/non_existent_orientation] - Failed: DID NOT RAISE ValidationError
FAILED tests/test_attributes.py::test_attributes[spec/invalid/image/non_existent_orientation_type] - Failed: DID NOT RAISE ValidationError
FAILED tests/test_attributes.py::test_attributes[spec/invalid/transforms/bad_projectAxis_insert_too_high_dim] - Failed: DID NOT RAISE ValidationError
FAILED tests/test_attributes.py::test_attributes[spec/invalid/transforms/bad_projectAxis_insert_too_many] - Failed: DID NOT RAISE ValidationError
FAILED tests/test_attributes.py::test_attributes[spec/invalid/transforms/bad_projectAxis_remove_too_high_dim] - Failed: DID NOT RAISE ValidationError
FAILED tests/test_attributes.py::test_attributes[spec/invalid/transforms/bad_projectAxis_remove_too_many] - Failed: DID NOT RAISE ValidationError
FAILED tests/test_attributes.py::test_attributes[spec/valid/image/many_space_axes] - jsonschema.exceptions.ValidationError: {'ome': {'version': '0.9.dev1...

Most of these are because they have now become valid, so I'll move them. But these two:

FAILED tests/test_attributes.py::test_attributes[spec/invalid/image/non_existent_orientation] - Failed: DID NOT RAISE ValidationError
FAILED tests/test_attributes.py::test_attributes[spec/invalid/image/non_existent_orientation_type] - Failed: DID NOT RAISE ValidationError

I don't understand why they are failing. Here's the orientation schema, which specifies that the strings must come from specific lists:

https://github.com/jni/ngff-spec/blob/af560df45c0aa987d537e128195bc2dcd454c0a4/schemas/axis_orientation.schema#L11-L43

and here's the relevant part of the files that are unexpectedly passing validation:

https://github.com/jni/ngff-spec/blob/af560df45c0aa987d537e128195bc2dcd454c0a4/tests/attributes/spec/invalid/image/non_existent_orientation.json#L16-L18

https://github.com/jni/ngff-spec/blob/af560df45c0aa987d537e128195bc2dcd454c0a4/tests/attributes/spec/invalid/image/non_existent_orientation_type.json#L26-L29

I'm a noob with jsonschema so I would appreciate any tips or advice here!

The development version that carries RFC-3 is 0.9.dev1. ome/ngff-spec#190 titles the specification 0.9.dev1 and its _version.schema enum holds that value; bioformats2raw#330 writes the same string. Renames the package py/ngff_zarr/v10 to v09 and its test module, the NgffVersion member V10DEV to V09dev1, and the version string in both ports. LATEST stays 0.6.dev4 and the version stays opt-in.

Update axes and cooordinate transformations schemas to remove axes restrictions as per RFC-3.

First, copied schema directly from RFC-4. Then, harmonised it to other schemas: - 2 spaces for indents - schema and ID at top - ID is NGFF url - add title and description - removed additionalproperties, metamodel, and version fields Added ref to orientation in axes schema and moved orientation def to top level.

- Add valid image data with axis orientation - Add invalid orientation attribute files - Add invalid orientation zarr folders - xfail duplicate orientation and orientation on non-space axes (these can't be easily expressed in jsonschema)

- index.md - Add 0.9.dev1 to version history - Update version string in all schemas - Update version in _version.py - Update version number on all examples - Update version string in omero valid test

jni · 2026-08-21T00:57:22Z

@joshmoore @clbarnes @jo-mueller This should be ready for review. I've also rebased my changes into logical commits to make review easier. Especially if you skip the last commit (which updates the version string in every file), the list of changes should be manageable.

clbarnes · 2026-08-21T10:42:58Z

 case_fnames = sorted(attrs_dir.rglob("*.json"))

-xfails = set()
+xfails = set([


Extremely minor point: can use a set literal {} here.

clbarnes · 2026-08-21T10:53:13Z

+  "value". Currently, "type" may only be "anatomical", and "value" may
+  only be one from the list given in [list of possible anatomical
+  orientation values](orientation-values). A specific orientation value or
+  its inverse MUST NOT appear more than once in a given coordinate system.


Could RECOMMEND TCZYX here for backwards-compatibility, if there's any benefit to that? Or alternatively, add a {hint} that axis ordering could affect performance of certain quries in combination with configuration of the array chunking/ sharding/ transposing.

@clbarnes I'm puzzled about the line you chose to make this comment on? I don't see why axis an orientation note would recommend anything about axis ordering?

At any rate, I think hints about performance can come in future iterations of the 0.9.devN series.

I am also puzzled by my choice of line here. Maybe I fat-fingered the touchpad.

clbarnes · 2026-08-21T10:57:54Z

-  - If there are three spatial axes where two correspond to the image plane (`yx`)
-    and images are stacked along the other (anisotropic) axis (`z`),
-    the spatial axes SHOULD be ordered as `zyx`.
+0. The length of the axis names MUST match the number of axes of the array.


I'd be inclined towards 1-basing for ordered lists. The audience is obviously technical but in text 1-based is much more common.

Oh, I don't mind fixing that, I didn't because I added it later and it renders as 1-based anyway:

So I suggest fixing that in later refinement passes also.

... But the wrong tick marks in point 5 should definitely be fixed 😂

ok I fixed both the numbering and the quotes.

sbesson · 2026-08-21T11:09:08Z

This line should probably be updated following RFC-3

fixed! 🙏

sbesson mentioned this pull request Aug 19, 2026

Report Modulo dimensions as separate axes (RFC-3) glencoesoftware/bioformats2raw#330

Open

kevinyamauchi mentioned this pull request Aug 19, 2026

add 0.9dev1 support ome-zarr-models/ome-zarr-models-py#475

Open

vboussot mentioned this pull request Aug 19, 2026

fix(py,ts): support OME-Zarr RFC-3 (arbitrary axis dimensions, names, types, ordering) fideus-labs/ngff-zarr#611

Open

jni changed the title ~~WIP: 0.9dev1~~ WIP: 0.9.dev1 Aug 20, 2026

vboussot mentioned this pull request Aug 20, 2026

test(py): RFC-3 conformance driver + reference-data integration fideus-labs/ngff-zarr#612

Open

This was referenced Aug 20, 2026

RFC-4: making orientation.schema.json usable as a validator ome/ngff#586

Open

RFC-4: the anatomical orientation vocabulary is no longer enforced ome/ngff#585

Open

fix(py): read the axes wherever the version keeps them fideus-labs/ngff-zarr#661

Merged

jni force-pushed the 0.9dev1 branch from 7da8abf to f414710 Compare August 21, 2026 00:05

jni added 8 commits August 21, 2026 10:38

Update spec text to include RFC-3 changes

9c1b163

Update spec text to include RFC4

08bab99

Remove number of axes or spatial axes restriction

ce324f0

Update axes and cooordinate transformations schemas to remove axes restrictions as per RFC-3.

Make formerly invalid files now valid since RFC-3

ddffb3b

Add conformance test files for RFC-4

2ae554b

- Add valid image data with axis orientation - Add invalid orientation attribute files - Add invalid orientation zarr folders - xfail duplicate orientation and orientation on non-space axes (these can't be easily expressed in jsonschema)

Don't include swap files in schemas list

8b9b069

Update version string everywhere

e042763

- index.md - Add 0.9.dev1 to version history - Update version string in all schemas - Update version in _version.py - Update version number on all examples - Update version string in omero valid test

jni force-pushed the 0.9dev1 branch from 3226d9b to e042763 Compare August 21, 2026 00:55

clbarnes approved these changes Aug 21, 2026

View reviewed changes

sbesson reviewed Aug 21, 2026

View reviewed changes

Remove reference to max 5-dimensions in the example hierarchy

9df947d

jni added 3 commits August 21, 2026 22:33

Consintently use single quotes for axis names in prose

e0e91fd

Use 1-indexing for numbered list in prose

874c6d7

Use set literal for set

98a80c5

vboussot mentioned this pull request Aug 21, 2026

The data model does not follow the schema of its own version fideus-labs/ngff-zarr#667

Open

Uh oh!

Conversation

jni commented Aug 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

notes

Uh oh!

github-actions Bot commented Aug 19, 2026

Automated Review URLs

Uh oh!

sbesson commented Aug 19, 2026

Uh oh!

clbarnes commented Aug 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

melissalinkert commented Aug 19, 2026

Uh oh!

jni commented Aug 20, 2026

Uh oh!

jni commented Aug 20, 2026

Uh oh!

jni commented Aug 21, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

jni commented Aug 19, 2026 •

edited

Loading

clbarnes commented Aug 19, 2026 •

edited

Loading